Documentation Guide#

The documentation for the Oklahoma NG911 GIS Toolkit for ArcGIS Pro is comprised of two main pieces, namely, the API documentation for the ng911ok package and the Toolkit documentation for the ArcGIS Toolbox.

API Documentation#

The API documentation is written in reStructuredText and built with Sphinx. It uses the PyData Sphinx Theme and that theme’s corresponding version of Sphinx Design.

Custom Sphinx Roles#

Note

As used by Sphinx, the term “role” denotes specially-interpreted text that may be rendered differently than the text around it. This is unrelated to the role attribute of the NG911Field and NG911FeatureClass classes.

In this section, the terms “Sphinx role” and “role attribute” will be used to distinguish between the two.

The following custom Sphinx roles are defined:

Sphinx Role

Rendered

Corresponds To

Example

ng911field

Field

NG911Field.role

:ng911field:`field_role_attribute`

ng911fc

Feature Class

NG911FeatureClass.role

:ng911fc:`feature_class_role_attribute`

ng911domain

Domain

NG911Domain.name

:ng911domain:`domain_name`

ng911ds

Feature Dataset

required or optional

:ng911ds:`required`

ng911tool

Validate Geodatabase

label attribute of tool classes in ng911ok.tools

:ng911tool:`Tool Name`

For :ng911field:, :ng911fc:, :ng911domain:, and :ng911ds:, if the text starts with a percent sign (%), that character itself will be removed, but whatever text that follows it will be preserved; this functionality is intended to be used only for demonstration purposes (e.g., to produce the contents of the “Rendered” column in the table above).

In the case of fields and feature classes, the provided role attribute will be replaced with the name attribute. This ensures that the correct field or feature class name will always be reflected when using these custom Sphinx roles, even if the name attributes change in a future version of the Standards.

In the case of tools, the rendered output will link to the corresponding tool class in ng911ok.tools, but the text itself will not be changed.

These custom Sphinx roles are implemented in the modules in /_ext and the stylesheets are located in /_static (where / denotes the Sphinx source root).

Toolkit Documentation#

The Toolkit documentation is written in Markdown.

Using Visual Studio Code with the Markdown All in One extension, the documentation can be exported as HTML every time the Markdown files are saved.